home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-02 / p_pascal.zip / READ.ME < prev   
Text File  |  1990-06-02  |  21KB  |  488 lines

  1. l
  2.                        ALL RIGHTS RESERVED.
  3.  
  4. DISCLAIMER:
  5.  
  6.      These programs are  provided to the public domain  as a ser-
  7.      vice  to   programmers.  They  may  be   copied  freely  and
  8.      distributed  for  educational  purposes  with  the following
  9.      restrictions:
  10.  
  11.      1. Commercial resale of  these programs, or incorporation of
  12.      these programs into other  systems for commercial resale, in
  13.      source code or  in compiled versions of the  source code, is
  14.      prohibited.
  15.  
  16.      2.  Charges for  reproduced copies  must be  limited to cost
  17.      (disks, postage and handling).
  18.  
  19.      3.  Any modifications  to the  programs from  the originally
  20.      distributed version  must be clearly indicated,  both in the
  21.      source  code and  the documentation.  Any such modifications
  22.      should  retain the  genealogy of  the program,  both in  the
  23.      source code, sign-on message, and documentation.
  24.  
  25.      4.  All  documentation  and   notices  supplied  with  these
  26.      programs must be included in any reproduced versions.
  27.  
  28.      5.  All warranties  connected with  these programs  are dis-
  29.      claimed. In particular, the author assumes no responsibility
  30.      that  the programs  will operate  as documented,  nor is the
  31.      author  responsible for  direct, indirect,  or consequential
  32.      damages.  Any  and  all  risk  associated  with  using these
  33.      programs, in whole or in part, is the user's.
  34.  
  35.  
  36. =================================================================
  37.  
  38. Note: Directions for using this  system are included below and in
  39. the a:\samples directory. For information about advanced versions
  40. of this  system, or about versions  customized to run efficiently
  41. on computers with different  architectures, contact the author at
  42. the address given below.
  43.  
  44. This  is  a  portable  Standard  Pascal  system,  with some C ex-
  45. tensions.  It implements  advanced Pascal  capabilities, such  as
  46. procedures  and  functions  passed   as  parameters,  and  allows
  47. "conformant arrays" to be passed  as pointers. Records and arrays
  48. are all automatically  packed down to the character  level. The C
  49. extensions, such  as masking and shifting  operations, the `halt'
  50. command,  the `system'  call, and  C-style file  inclusion during
  51. translation,  are illustrated  by examples  in the  demonstration
  52. programs of the a:\samples directory.  This version of the system
  53. is limited to  seven open data and textfiles  at any point during
  54. program execution.  The full version, that  permits as many files
  55. as available from your operating  system, and comes with portable
  56. ANSI C source code, can be ordered from the address at the end of
  57. this file.
  58.  
  59. Modern college-level  Pascal programming textbooks,  such as "Oh!
  60. Pascal", by  Cooper and Clancy, give  examples of Pascal programs
  61. that will run on this system.
  62.  
  63. The enclosed  Pascal to p-code translator  and p-code interpreter
  64. is a companion system to the  Pascal to C translator, that can be
  65. ordered from the address at the end of this file.
  66.  
  67. These portable systems are written entirely in ANSI C. The Pascal
  68. to C translator is based on the p-code interpreter, but generates
  69. optimizable C code that runs  almost as fast as programs compiled
  70. directly from C code. The source is written to be compiled easily
  71. under the DOS 3.2 and  later operating systems (and other systems
  72. also, with minor changes in the "pascal.h" and "p-code.h" files).
  73.  
  74. K & R versions of the system can be obtained from the author.
  75.  
  76. As  a  demonstration  of  this,  the  "primes.exe" program in the
  77. \samples  directory  of  this  diskette  was  compiled  from  the
  78. "\samples\primes.pas" program after a Pascal to C translation.
  79.  
  80.  
  81. =================================================================
  82.  
  83. DIRECTIONS
  84.  
  85. The following reserved words and standard names are recognized by
  86. the system and operate in a standard fashion (with exceptions for
  87. pack and unpack):
  88.  
  89. Standard Names:
  90.  
  91. false,    true,     input,    output,   get,      put,      reset,
  92. rewrite,  read,     write,    pack,     unpack,   new,      dispose,
  93. readln,   writeln,  page,     mark,     release,  halt,     abs,
  94. sqr,      round,    trunc,    odd,      ord,      chr,      pred,
  95. succ,     eof,      eoln,     system,   sin,      cos,      exp,
  96. sqrt,     ln,       arctan,   integer,  real,     char,     boolean,
  97. text,     nil,      maxint,   sethigh,  ordmaxchar
  98.  
  99.  
  100. Reserved Words:
  101.  
  102. if,       do,       of,       to,       in,       or,       and,
  103. not,      xor,      shl,      shr,      end,      for,      var,
  104. div,      mod,      set,      then,     else,     with,     goto,
  105. case,     type,     file,     begin,    until,    while,    array,
  106. const,    label,    repeat,   record,   downto,   packed,   forward,
  107. program,  function, procedure
  108.  
  109.  
  110. 1) Typing `TRANSLATE <Enter>' will  bring up the following direc-
  111. tions for use:
  112.  
  113.  
  114. Portable ISO Standard Pascal in C, version 3.8, May 31 1990.
  115. All rights reserved.
  116.  
  117. The calling sequence is
  118.  
  119.   translator  source.pas  object.pcd  [optional directives]
  120. or
  121.   translator con  object.pcd /c+  [optional directives]
  122.  
  123. with `source.pas'  or `con' (the  keyboard) as the  Pascal source
  124. code file and `object.pcd' serving as the output `p-code' file.
  125.  
  126. The source and  output file names are optionally  followed by one
  127. or more Pascal translator directives from the list below:
  128.  
  129. /c+ Generate P-Code                /l- Turn Off Program Listing
  130. /o+ Send P-Code to Source Listing  /t+ Print Translator Symbol Tables
  131. /d+ All Run-Time Checks            /y+ Special Error Messages
  132. /z+ Run-Time Zero Division Checks  /s+ Run-Time Stack Checks
  133. /r+ Run-Time Set Element/Index/Pointer Range Checks
  134.  
  135. Note  that c-  (syntax-checking only)  is the  default c  option.
  136. Here,  the  usual  C  command-line  convention  applies, in which
  137. options are separated by blanks and  are preceded by either a `-'
  138. or a `/'.
  139.  
  140.  
  141. 2)  Typing `INTERPRET <Enter>' will bring up the following direc-
  142. tions for use:
  143.  
  144. Near arrays Pascal P-Code interpreter, version 3.8, May 31 1990.
  145. All rights reserved.
  146.  
  147. The correct calling sequence is:
  148.  
  149.  interpreter a_program.pcd [path1][pr1] ... [pathn][prn]
  150.  
  151. with  executable p-code  stored in  the file  a_program.pcd and n
  152. [optional] external files pr1 through  prn. Files pr1 through prn
  153. may have path prefixes appropriate  to your operating system. The
  154. pr1  through  prn  names  are  declared  in  the Pascal "Program"
  155. statement, and any information about the directories in which the
  156. files are located  is included on the command  line. The standard
  157. Pascal Input and Output files behave exactly like the C stdin and
  158. stdout files.
  159.  
  160. A more elaborate explanation follows below.
  161.  
  162.  
  163. NOTES ON USING THE TRANSLATOR:
  164.  
  165.  
  166. FEATURES AND RESTRICTIONS
  167.  
  168. This is a standard Pascal in C implementation compatible with the
  169. Pascal taught in college textbooks  such as Oh! Pascal! by Cooper
  170. and Clancy. The C implementation is portable, which means that it
  171. will compile and  operate correctly on any computer  with a stan-
  172. dard ANSI C compiler, and  will automatically adjust to different
  173. CPU architectures.
  174.  
  175. This implementation limits sets to 64 members on 16-bit machines,
  176. and string  constants to no  more than 80  characters apiece. Any
  177. mix  of upper  and lower  case identifiers  and reserved words is
  178. legal,  but only  the first  eight characters  of identifiers are
  179. significant. European ascii alphabet letters may be used in iden-
  180. tifiers. The  predeclared constant "Maxint" has  a value of 32767
  181. for 16-bit CPUs  like the 8086, which means  that any long arith-
  182. metic  must  be  done  using  REAL  numbers.  Anticipated  future
  183. releases of this system will support long arithmetic.
  184.  
  185. Additional  minor restrictions:  procedures and  functions may be
  186. passed as parameters, with the restrictions mentioned in standard
  187. Pascal textbooks  for this capability;  e. g., 'Read',  'Readln',
  188. 'Write', and 'Writeln'  may not be passed as  parameters, but may
  189. occur within  procedures/functions passed as  parameters. See the
  190. "prfnparm.pas" program in the  \samples directory for examples of
  191. functions  and procedures  passed as  parameters and  the use  of
  192. textfiles.
  193.  
  194. The  `halt' or  `halt(integer_value)' command,  available on many
  195. Pascal systems  as a nonstandard capability,  is also implemented
  196. on this system, and behaves  like the C `exit' procedure. ('halt'
  197. with no parameter  is translated to `exit(0)', and  `halt' with a
  198. parameter is the corresponding call on `exit').
  199.  
  200. The 'Packed' and  'Unpacked' keywords may be used,  but they have
  201. no effect;  instead, all character and  boolean arrays are stored
  202. as packed  character arrays. Pack and  Unpack are implemented for
  203. standard Pascal data types, but  the packing of Boolean arrays as
  204. `bit  arrays' is  not supported.  An example  of "do it yourself"
  205. packing and unpacking of bit  arrays using the shifting and mask-
  206. ing   operators   is   included   in   the   \samples   directory
  207. ("truefalse.pas").
  208.  
  209. See  the yesno.pas  program in  the a:\samples  directory for ex-
  210. amples of  string assignment and comparison  (ISO standard Pascal
  211. version).
  212.  
  213. A  "System(packed_char_array)" function identical  in behavior to
  214. the C  version of "system(char *)"  is implemented. If you  use a
  215. Pascal packed char array instead of a string constant as argument
  216. to the "System" function, be sure to intialize your array proper-
  217. ly with a blank string constant of the correct size.
  218.  
  219. This new  version supports standard  Pascal data and  text files,
  220. both  as  external  Pascal  files  and  as  local  files that are
  221. automatically deleted at the end  of the procedure or function in
  222. which  they  are  declared.  The  external  Pascal file names are
  223. limited  to  eight  letters  and  must  appear  in the first line
  224. "program xxxxx(a, b, ...);" statement. (These file namea may also
  225. apear on the command line with Unix or Dos path prefixes.)
  226.  
  227. Pascal "Reset" is implemented by  rewinding the file and then is-
  228. suing  a Pascal  "GET." A  Pascal "Rewrite"  deletes the file and
  229. then reopens it.
  230.  
  231. The standard Pascal "New"  and "Dispose" procedures are available
  232. for  acquiring individual  data nodes  and returning  them to the
  233. Pascal heap. (The "optimized" use of  New, in which only parts of
  234. a record are  allocated IS supported, but  users are cautioned to
  235. debug their programs  first using the simple version  of New.) In
  236. addition, "Mark" and "Release" are available for use in returning
  237. entire blocks of data to  the heap, rather than individual nodes.
  238. Programs can  be written using only  "New" and "Dispose", without
  239. mention  of  "Mark"  and  "Release".  Or,  "New" (and optionally,
  240. "Dispose") can be used in combination with "Mark" and "Release".
  241.  
  242. However,  while "New"  and "Dispose"  are relatively well-behaved
  243. operations,  "Mark" and  "Release" have  to be  used carefully as
  244. paired operations  that have side-effects. One  of these side ef-
  245. fects is  that all data  nodes acquired by  "New" after a  "Mark"
  246. operation are automatically disposed of by the call on "Release".
  247. Furthermore, calls  on "Mark" and  "Release" are only  defined if
  248. they  are paired  so each  call on  "Mark" is  balanced by a cor-
  249. responding  call on  "Release". (The  a:\samples listtest.pas and
  250. newtest.pas programs are examples of their use.)
  251.  
  252. The  enclosed   "Near  arrays"  version  of   the  Pascal  p-code
  253. interpreter has  approximately 15,000 bytes  of Pascal heap  area
  254. available for  "New" and "Dispose", the  "Far arrays" version has
  255. 62,400 bytes, and the "Huge arrays" version has 142,400 bytes.
  256.  
  257. Some small source program examples  are included in the "samples"
  258. directory on  this diskette. They illustrate  the general form of
  259. programs accepted  by the translator and  the required translator
  260. options directives to precede programs.
  261.  
  262. =================================================================
  263.  
  264. TRANSLATOR OPTIONS:
  265.  
  266. In this  Pascal system, translator  options can appear  either on
  267. the command line,  as noted above, or within  the program. Pascal
  268. options behave  like C pragmas. Program  examples in the \samples
  269. file  illustrate the  use of  translator options.  In particular,
  270. "pi.pas" shows how to turn the translator listing on and off dur-
  271. ing translation of that  program, and "factorial.pas" illustrates
  272. use  of the  {$i+'file_name'} option  for including  files within
  273. your programs.
  274.  
  275.   (*$ ... *) or {$ ... }
  276.  
  277. where the " ... " in the middle is some sequence of the following
  278. options separated by commas:
  279.  
  280.  
  281.        a+ causes division by zero tests to be inserted before all
  282.        all run-time code for real and integer division.
  283.  
  284.        c+ causes p-code  to be written to the  ".pcd" file. If c+
  285.        does  not appear,  or if  c- or  c is  written, the source
  286.        program will  be checked for  correctness, but not  trans-
  287.        lated.
  288.  
  289.        d+ causes the translator to put  all a+, r+, and s+ checks
  290.        into  the  run-time  code.  These  checks  are  useful for
  291.        program debugging,  but can cause programs  to run slowly.
  292.        They  are partly  responsible for  Pascal's reputation for
  293.        slowness.  Eliminating  these  checks  via  the  d- option
  294.        improves  program  execution  speed  and  allows "flexible
  295.        dimension" arrays (when no  range checking occurs). The d+
  296.        option  can  be  turned  on  and  off  locally within your
  297.        program by following it with a d- option.
  298.  
  299.        i+ causes the file whose quoted name follows to be read by
  300.        the translator:
  301.  
  302.         i.  e., {$i+'a:\samples\round.p'}
  303.  
  304.        includes the  round.p file at  that point in  the program.
  305.        The  file source  code has  to be  to be  correct for that
  306.        point  in the  program where  its insertion  occurs. Up to
  307.        seven levels  of file inclusion  from any source  file are
  308.        allowed by the system. (For examples  of how to use the i+
  309.        option,  refer to  the 'a:\samples\factorial.pas'  and the
  310.        'a:\samples\truefalse.pas' files. The  C '#include' pragma
  311.        behaves in similar fashion.)
  312.  
  313.        l+ causes  the program to  be listed to  the "stdout" file
  314.        (the monitor screen). The  listing can be re-directed from
  315.        the screen to the line printer using the ">" redi- rection
  316.        operator  on the  command line.  l+ is  the default option
  317.        (the listing  will appear if  l+ is omitted).  To turn off
  318.        the listing, use l-. Programs will translate several times
  319.        faster with the screen listing disabled.
  320.  
  321.        o+ causes  the translator to route  its translation of the
  322.        source program  to the stdout  file, causing each  execut-
  323.        able source statement to be followed by the p-code that it
  324.        generates (the ".pcd" file will  be empty as a result, but
  325.        must still be mentioned on the translator's command line).
  326.        Default option is o-.
  327.  
  328.        r+ causes the translator to  insert run-time tests for set
  329.        element-,  loop index-,  and pointer-in-range correctness.
  330.        Setting r- or d- disables these tests.
  331.  
  332.        s+ causes  the run-time system to  test for stack overflow
  333.        on entry to all procedures and functions. Setting s- or d-
  334.        turns off these tests.
  335.  
  336.        t+ causes the translator to  write out its internal tables
  337.        listing declared  constants, procedures, and  functions at
  338.        the end  of the translation  pass. Its use  is to discover
  339.        what  the translator  believes the  program variables  and
  340.        procedures to be. Default option is t-.
  341.  
  342.  
  343. Command line calling sequences for the translator and interpreter
  344. are as described below. (See also the "a:do.bat" file.)
  345.  
  346. For the translator:
  347. ==================================================================
  348.  
  349.     translator  your_source_code.pas  p_code_output.pcd
  350.  
  351. or
  352.  
  353.     translator con  p_code_output.pcd
  354.  
  355. ==================================================================
  356.  
  357. Note that the  .pcd file extension for the  output p-code file in
  358. the example is necessary to  interface properly with both the in-
  359. terpreter and the C code generator programs.
  360.  
  361. With `con' on the command line as illustrated above, programs can
  362. be typed in from the keyboard  and translated one line at a time,
  363. but editing is limited to the current line only. Refer to the DOS
  364. manual description of the "copy  con output_file" command for in-
  365. formation about how to use the console keyboard for program input
  366. to the  translator. In particular,  "control-Z" or ^Z  is used as
  367. the end of file mark to terminate source programs.
  368.  
  369. Files external to the program  are named in standard Pascal style
  370. on the "Program xxxxx(Input, Output, File1, File2);" line of your
  371. Pascal  program. These  external files  are names  of up to eight
  372. letters  each (the  same as  Pascal identifiers),  and they match
  373. file names (preceded by optional operating system pathnames) that
  374. ap- pear on the command line of your program. Thus, for example,
  375.  
  376.          Program Fileptrs(Input, Output, Prr);
  377.          ....
  378.          ....
  379.          END.
  380.  
  381. can be called by a command line sequence of the form:
  382.  
  383.          interpreter fileptrs.pcd c:\xxx\prr
  384.  
  385. or
  386.  
  387.          interpreter fileptrs.pcd a:\yyy\zzzz.prr
  388.  
  389. or even
  390.  
  391.          interpreter fileptrs.pcd prr
  392.  
  393. depending on the  file path designation that you,  the user, find
  394. convenient to use.
  395.  
  396. Translator  listings  are  sent  to  the  screen,  unless DOS I/O
  397. redirection is used:
  398.  
  399. =================================================================
  400.  
  401.   translator source.pas  object.pcd  >  lpt1 (* parallel printer *)
  402.  
  403. or
  404.  
  405.   translator source.pas  object.pcd  >  com1 (* serial printer *)
  406.  
  407. or
  408.  
  409.   translator source.pas  object.pcd  >  a:listing.asc
  410.  
  411. =================================================================
  412.  
  413.  
  414.  
  415. NOTES ON USING THE Interpreter:
  416.  
  417. Interpreter command line with optional files in brackets:
  418.  
  419. =================================================================
  420.  
  421.    interpreter  p_code_input.pcd [path1][file1] [path2][file2]
  422.  
  423. =================================================================
  424.  
  425. The interpreter also has available  the standard Pascal Input and
  426. Output files,  known in the  C language as  stdin and stdout.  So
  427. programs translated for the interpreter can access Input (stdin),
  428. Output (stdout),  and as many external  and internal Pascal files
  429. as  your  system  will  allow.  See  the a:\samples directory for
  430. examples of how to use files.
  431.  
  432. Note that the interpreter has some limitations, most important of
  433. which is that sets can have up  to 64 members. This is a complete
  434. Standard Pascal  otherwise. It is intended  as a teaching system,
  435. with the  p-code interpreter to  be used by  students in compiler
  436. courses. Thus, the p-code output  from the translator is in ascii
  437. format, so that it can be  inspected and compared with the source
  438. code  and used  in conjunction   with the  source code  to p-code
  439. cross-reference generated in the translator listings.
  440.  
  441. =================================================================
  442.  
  443. SOURCES OF INFORMATION:
  444.  
  445. The reference for a previous  version of the Pacal translator and
  446. its p-code interpreter, including  comments for the Pascal source
  447. code, is in the book:
  448.  
  449.    Pemberton, S. Pascal Implementation. Ellis-Horwood Publishers,
  450.       Ltd., England, 1981.
  451.  
  452. The  authors  of  the  Pascal  version  of  the  portable  Pascal
  453. translator are U.  Ammann, K. Nori, and C.  Jacobi. K. Jensen, N.
  454. Wirth, and C.  Jacobi wrote the Pascal version  of the p-code in-
  455. terpreter.
  456.  
  457. The ANSI C version of these systems implements an advanced p-code
  458. that is not  compatible with the p-code of  the Pascal system and
  459. provides numerous  capabilities, e. g.,  procedures and functions
  460. passed  as parameters,  conformant arrays,  full data  files, not
  461. included in the Pascal version.
  462.  
  463. Translator  error  messages  use  the  error  number  format that
  464. appears  in the  Pascal User  Manual listed  below and in several
  465. Pascal and C compilers as well:
  466.  
  467.     Jensen, K. and Wirth,  N.  Pascal  User  Manual  and  Report.
  468.          Springer Publishing Co., 1974.
  469.  
  470. =================================================================
  471.  
  472. As of June, 1990, the price of the DOS version of the full Pascal
  473. to P-Code Translator/Interpreter with C source code was $50 post-
  474. paid, and the Pascal to C  translator with C source code was also
  475. $50 postpaid. (Specify 3-1/2" or  5-1/4" diskettes; if no size is
  476. specified, 5-1/4" diskettes will be  sent. Payment is by check or
  477. money order.  Orders from outside  the U. S.  please add $10  per
  478. order for shipping.)
  479.  
  480.  
  481. Address for orders and inquiries:
  482.  
  483.     Victor Schneider
  484.     Suite 3QD
  485.     291 Summit Avenue
  486.     Brighton, MA 02146
  487.     USA
  488.